home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / libs / shadowlib.lha / shadow / Docs / ShadowLibFuncs.doc < prev    next >
Text File  |  1992-11-13  |  35KB  |  1,005 lines
  1.                          Shadow.lib  Documentation
  2.                             Library Version 5.0
  3.  
  4.                               By David Navas
  5.                          Updated:  13 Nov 1992
  6.  
  7.                       Copyright © 1992 by David Navas
  8.                             All Rights Reserved
  9.  
  10. All functions except for SPrintfCallback take their arguments on the
  11. stack.
  12.  
  13. NAME
  14.       CreateInstance -- Creates in instance of a class.
  15.  
  16. SYNOPSIS
  17.       object = CreateInstance( pClass, className, metaName, ..., METHOD_END)
  18.         d0                                           < args on stack >
  19.  
  20. FUNCTION
  21.       Creates an instance of the described class.  Classes may be either
  22.       a private class, a public class, or a public meta.  If pClass is
  23.       non-NULL, then that class is used to create the instance.  If
  24.       metaName is NULL, then the className is used as a name for the
  25.       meta stored on the ShadowBase->sb_metaTree (which is what will be
  26.       used to create the instance).  Otherwise the metaName is used as
  27.       the name of the meta and className is used as the name for a class
  28.       on the meta's ATTR_INSTANCETREE which is the class that it will use
  29.       to create the instance.
  30.  
  31.       The arguments are the arguments that are passed to the
  32.       METH_INIT method of the object that is created.
  33.  
  34.       Complicated?
  35.  
  36.       Three possibilities:
  37.          CreateInstance(myPrivateClass, NULL, NULL, lots-of-args,
  38.                                                     METHOD_END);
  39.             - creates instance of myPrivateClass
  40.  
  41.          CreateInstance(NULL, META_CLASS, NULL, lots-of-args, METHOD_END);
  42.  
  43.             - creates a new Class whose cob_class is METACLASS
  44.                [createSubClass() is preferred!]
  45.  
  46.          CreateInstance(NULL, ROOT_CLASS, META_CLASS, lots-of-args,
  47.                                                     METHOD_END);
  48.             - creates an instance of ROOT_CLASS, where ROOT_CLASS is a class
  49.               found in the META_CLASS' ATTR_INSTANCETREE.
  50.  
  51.  
  52. INPUTS
  53.       META        pClass; - a pointer to the private class that you want
  54.                              an instance of.  If NULL, then use the
  55.                              className and metaName to find a public class.
  56.       char    *className; - the name of the public class.
  57.       char     *metaName; - the name of the public meta that the class can
  58.                              be found in.  If NULL, then the className is
  59.                              treated as the name of a public meta that you
  60.                              want an instance of.
  61.       .
  62.       .  <--- other arguments as per the class' METH_INIT method.
  63.       .
  64.  
  65. OUTPUTS
  66.       void       *object; - the instance, or the return value from the
  67.                              METH_INIT of the particular class.  As the
  68.                              programmer, you may want to change what that
  69.                              method returns.  For all included classes,
  70.                              the METH_INIT returns the object.
  71.                             NULL if error (for instance, class could not
  72.                              be found).
  73.  
  74. RESULT
  75.       A new Instance (OBJECT) is formed.
  76.  
  77. BUGS
  78.       none known.
  79.  
  80. NOTES
  81.  
  82. SEE ALSO
  83.       METH_CREATE method in ShadowLibraryMethods.doc
  84.       METH_INIT method in ShadowLibraryMethods.doc
  85.       CreateSubClass()
  86.       RemoveObject()
  87.  
  88. NAME
  89.       CreateSubClass -- Creates a sub-class of a class.
  90.  
  91. SYNOPSIS
  92.       object = CreateSubClass( pClass, className, metaName, ..., METHOD_END)
  93.         d0                                           < args on stack >
  94.  
  95. FUNCTION
  96.       Creates a subclass of the described class.  Classes may be either
  97.       a private class, a public class, or a public meta.  If pClass is
  98.       non-NULL, then that class is used to create the subclass.  If
  99.       metaName is NULL, then the className is used as a name for the
  100.       meta stored on the ShadowBase->sb_metaTree (which is what will be
  101.       used to create the submeta).  Otherwise the metaName is used as
  102.       the name of the meta and className is used as the name for a class
  103.       on the meta's ATTR_INSTANCETREE tree which is the class that it will
  104.       use to create the subclass.
  105.  
  106.       The arguments are the arguments that are passed to the METH_SUB
  107.       method of the class that is being sub-classed.
  108.  
  109.       Complicated?
  110.  
  111.       Three possibilities:
  112.          CreateSubClass(myPrivateClass, NULL, NULL, lots-of-args,
  113.                                                     METHOD_END);
  114.             - creates subclass of myPrivateClass
  115.  
  116.          CreateSubClass(NULL, META_CLASS, NULL, lots-of-args, METHOD_END);
  117.  
  118.             - creates a Meta as a submeta of META_CLASS
  119.  
  120.          CreateSubClass(NULL, ROOT_CLASS, META_CLASS, lots-of-args,
  121.                                                     METHOD_END);
  122.             - creates a subclass of ROOT_CLASS, where ROOT_CLASS is a class
  123.               found in the META_CLASS' ATTR_INSTANCETREE.
  124.  
  125.       Typically, the arguments are similar to the following:
  126.          CreateSubClass(NULL, PROCESS_CLASS, META_CLASS,
  127.                                              MY_CLASS_NAME,
  128.                                              NULL,          // The superclass
  129.                                                             // pointer which
  130.                                                             // defaults to the
  131.                                                             // passed class --
  132.                                                             //  PROCESS_CLASS.
  133.                                              myNewAttrs,
  134.                                              myNewMethods,
  135.                                              METHOD_END);
  136.  
  137.  
  138. INPUTS
  139.       META        pClass; - a pointer to the private class that you want
  140.                              a subclass of.  If NULL, then use the
  141.                              className and metaName to find a public class.
  142.       char    *className; - the name of the public class.
  143.       char     *metaName; - the name of the public meta that the class can
  144.                              be found in.  If NULL, then the className is
  145.                              treated as the name of a public meta that you
  146.                              want a subclass of.
  147.       .
  148.       .  <--- other arguments as per the class' meta's METH_SUB method.
  149.       .
  150.  
  151. OUTPUTS
  152.       void       *object; - the subclass, or the return value from the
  153.                              METH_SUB of the particular class' meta.  As
  154.                              the programmer, you may want to change what
  155.                              that method returns.  For all included
  156.                              metas, the METH_SUB returns the class.
  157.                             NULL if error (for instance, class could not
  158.                              be found).
  159.  
  160. RESULT
  161.       A new subclass is formed.
  162.  
  163. BUGS
  164.       none known.
  165.  
  166. NOTES
  167.  
  168. SEE ALSO
  169.       METH_SUB method in ShadowLibraryMethods.doc
  170.       CreateInstance()
  171.       RemoveObject()
  172.  
  173. NAME
  174.       DoShadow -- Front-end to DSM()
  175.  
  176. SYNOPSIS
  177.       result = DoShadow( object, class, method, ..., METHOD_END)
  178.         d0                               < args on stack >
  179.  
  180. FUNCTION
  181.       This function is the front-end to DSM().  As such, it is the
  182.       preferred way of invoking methods on objects.
  183.  
  184.       This routine checks for a valid object, and returns NULL if the
  185.       passed object is NULL.  If the passed class is NULL, the class is
  186.       set to object->cob_class.  If this is also NULL, then the function
  187.       returns NULL.
  188.  
  189.       If there is both a valid object and a valid class, DSM() is called
  190.       via:
  191.          DSM(INVOKE_FIND_METHOD, &object)
  192.  
  193.  
  194. INPUTS
  195.       OBJECT             object; - the object to send the method to.
  196.                                     If NULL, function returns NULL
  197.       META                class; - the first "class" to check for the
  198.                                     method.  This allows you to send
  199.                                     a method to an arbitrary Class....
  200.                                     However, to send the method to a
  201.                                     superclass, please use the
  202.                                     DoSuper*() alternatives below.
  203.                                    if NULL, class is set to
  204.                                     object->cob_class.  If this is
  205.                                     NULL, function returns NULL.
  206.       char              *method; - pointer to the selector string.
  207.       .
  208.       .  <--- other arguments to your method.
  209.       .
  210.  
  211. OUTPUTS
  212.       void *result; - result from DSM()
  213.  
  214.  
  215. RESULT
  216.       Result is dependent on the method invoked.
  217.  
  218. BUGS
  219.       none known.
  220.  
  221. NOTES
  222.  
  223. SEE ALSO
  224.       DSM()
  225.       ShadowLibraryMethods.doc and Introduction.doc have copious examples
  226.       of the usage of this function.
  227.  
  228. NAME
  229.       DoShadowAsync -- Front-end to DSM()
  230.  
  231. SYNOPSIS
  232.       result = DoShadowAsync( object, class, method, ..., METHOD_END)
  233.         d0                                    < args on stack >
  234.  
  235. FUNCTION
  236.       This function is another front-end to DSM().  It is the preferred
  237.       way of invoking asynchronous methods on objects.
  238.  
  239.       All validity checks done by DoShadow are also performed by
  240.       DoShadowAsync.
  241.  
  242.       DSM() is called in the following manner by this stub routine:
  243.  
  244.             DSM(INVOKE_FIND_METHOD | INVOKE_FORCE_ASYNC, &object)
  245.  
  246.       Notice the INVOKE_FORCE_ASYNC flag, the only substantial difference
  247.       between DoShadow() and DoShadowAsync().  Please refer to the docs
  248.       on DSM(), the Introduction.doc, or the ShadowLibraryMethods.doc
  249.       for more details on what these flags mean.  The flags themselves
  250.       are located in messages.h
  251.  
  252. INPUTS
  253.       OBJECT             object; - the object to send the method to.
  254.                                     If NULL, function returns NULL
  255.       META                class; - the first "class" to check for the
  256.                                     method.  This allows you to send
  257.                                     a method to the superClass...
  258.                                     if NULL, class is set to
  259.                                      object->cob_class.  If this is
  260.                                      NULL, then the function returns
  261.                                      NULL.
  262.       char              *method; - pointer to the selector string.
  263.       .
  264.       .  <--- other arguments to your method.
  265.       .
  266.  
  267. OUTPUTS
  268.       void *result; - result from DSM()
  269.  
  270.  
  271. RESULT
  272.       Result is dependent on the method invoked.
  273.  
  274. BUGS
  275.       none known.
  276.  
  277. NOTES
  278.       This is different from the DoShadow() function in that the method
  279.       is invokedd asynchronously from the calling process.  for a
  280.       discussion on what this means, see the Introduction.doc
  281.  
  282. SEE ALSO
  283.       DSM()
  284.       Introduction.doc has some  examples of the usage of this function.
  285.  
  286. NAME
  287.       DoShadowHintProcess -- Front-end to DSM()
  288.  
  289. SYNOPSIS
  290.       result = DoShadowHintProcess( process, object, class,
  291.                                      method, ..., METHOD_END)
  292.         d0                             < args on stack >
  293.  
  294. FUNCTION
  295.       This function is another front-end to DSM().  Unlike its
  296.       DoShadow() and DoShadowAsync() partners, this function attempts
  297.       to invoke the method in the passed process.
  298.  
  299.       However, the process object will only be used as a substitute
  300.       for the mtag_procObject that was passed in the METHOD_TAGS (set
  301.       in the SetupMethodTags() call, probably) to the class definition
  302.       (during METH_SUB or CreateSubClass()).
  303.  
  304.       This means, essentially, that if the method was not defined to
  305.       run in another process, the passed process will be ignored.  In
  306.       addition, if the message is not forced to be either synchronous or
  307.       asynchronous (in those cases the new process would definitely
  308.       be used to run the method), the passed process has its superclass
  309.       hierarchy checked just like a normal procObject would.
  310.  
  311.       Essentially, if the process belongs to a class that is the same
  312.       class, or a subclass of the same class, as the method invoker's
  313.       task, then the passed process is not used, the method is invoked
  314.       as a function instead.  This allows GUI-process methods to run in a
  315.       subclassed ASL-process without resorting to the relatively high
  316.       overhead of setting up messages and task switching.
  317.  
  318.       As with its other DoShadow*() partners, this function checks for a
  319.       valid object, and returns NULL if none.  If there is no valid class,
  320.       class is set to object->cob_class.  If this is NULL, then the
  321.       function returns NULL.
  322.  
  323.       Then, DSM() is called via:
  324.             DSM(INVOKE_FIND_METHOD | INVOKE_WITH_PROCESS, &object)
  325.  
  326.  
  327. INPUTS
  328.       OBJECT            process; - the process object to try invoking the
  329.                                     the method in.
  330.       OBJECT             object; - the object to send the method to.
  331.                                     If NULL, function returns NULL
  332.       META                class; - the first "class" to check for the
  333.                                     method.  This allows you to send
  334.                                     a method to the superClass...
  335.                                     if NULL, class is set to
  336.                                      object->cob_class.  If this is
  337.                                      NULL, function returns NULL.
  338.       char              *method; - pointer to the selector string.
  339.       .
  340.       .  <--- other arguments to your method
  341.       .
  342.  
  343. OUTPUTS
  344.       void *result; - result from DSM()
  345.  
  346.  
  347. RESULT
  348.       Result is dependent on the method invoked.
  349.  
  350. BUGS
  351.       none known.
  352.  
  353. NOTES
  354.  
  355. SEE ALSO
  356.       DSM()
  357.       DoShadow()
  358.       Introduction.doc has some examples of the usage of this function.
  359.  
  360. NAME
  361.       DoShadowInProcess -- Front-end to DSM()
  362.  
  363. SYNOPSIS
  364.       result = DoShadowInProcess( process, object, class,
  365.                                   method, ..., METHOD_END)
  366.         d0                          < args on stack >
  367.  
  368. FUNCTION
  369.       This function is another front-end to DSM() like its twin
  370.       "DoShadowHintProcess".
  371.  
  372.       This process, unlike DoShadowHintProcess, forces a synchronous
  373.       message across threads, with the actual method being called
  374.       at the other end.
  375.  
  376.       As with its other DoShadow*() partners, this function checks for a
  377.       valid object, and returns NULL if none.  If there is no valid class,
  378.       class is set to object->cob_class.  if this is NULL, then the
  379.       function returns NULL.
  380.  
  381.       Then, DSM() is called via:
  382.             DSM(INVOKE_FIND_METHOD | INVOKE_WITH_PROCESS | INVOKE_FORCE_SYNC,
  383.                 &object)
  384.  
  385.  
  386. INPUTS
  387.       OBJECT            process; - the process object to invoke the
  388.                                     the method in.
  389.       OBJECT             object; - the object to send the method to.
  390.                                     If NULL, function returns NULL
  391.       META                class; - the first "class" to check for the
  392.                                     method.  This allows you to send
  393.                                     a method to the superClass...
  394.                                     if NULL, class is set to
  395.                                      object->cob_class.  If this is NULL,
  396.                                      then the function returns NULL.
  397.       char              *method; - pointer to the selector string.
  398.       .
  399.       .  <--- other arguments to your method
  400.       .
  401.  
  402. OUTPUTS
  403.       void *result; - result from DSM()
  404.  
  405.  
  406. RESULT
  407.       Result is dependent on the method invoked.
  408.  
  409. BUGS
  410.       none known.
  411.  
  412. NOTES
  413.  
  414. SEE ALSO
  415.       DSM()
  416.       DoShadow()
  417.       DoShadowHintProcess()
  418.       Introduction.doc has some examples of the usage of this function.
  419.  
  420. NAME
  421.       DoShadowInProcessAsync -- Front-end to DSM()
  422.  
  423. SYNOPSIS
  424.       result = DoShadowInProcessAsync( process, object, class,
  425.                                        method, ..., METHOD_END)
  426.         d0                               < args on stack >
  427.  
  428. FUNCTION
  429.       This function is another front-end to DSM(), similar to
  430.       DoShadowHintProcess() and DoShadowInProcess().  It forces
  431.       a method to be run in the passed process asynchronously from the
  432.       caller.
  433.  
  434.       As with its other DoShadow*() partners, this function checks for a
  435.       valid object, and returns NULL if none.  If there is no valid class,
  436.       class is set to object->cob_class.  If this is NULL, then the
  437.       function returns NULL.
  438.  
  439.       Then, DSM() is called via:
  440.             DSM(INVOKE_FIND_METHOD | INVOKE_WITH_PROCESS | INVOKE_FORCE_ASYNC,
  441.                 &object)
  442.  
  443.  
  444. INPUTS
  445.       OBJECT            process; - the process object to invoke the
  446.                                     the method in.
  447.       OBJECT             object; - the object to send the method to.
  448.                                     If NULL, function returns NULL
  449.       META                class; - the first "class" to check for the
  450.                                     method.  This allows you to send
  451.                                     a method to the superClass...
  452.                                     if NULL, class is set to
  453.                                      object->cob_class.  If this is NULL,
  454.                                      then the function returns NULL.
  455.       char              *method; - pointer to the selector string.
  456.       .
  457.       .  <--- other arguments to your method
  458.       .
  459.  
  460. OUTPUTS
  461.       void *result; - result from DSM()
  462.  
  463.  
  464. RESULT
  465.       Result is dependent on the method invoked.
  466.  
  467. BUGS
  468.       none known.
  469.  
  470. NOTES
  471.  
  472. SEE ALSO
  473.       DSM()
  474.       DoShadow()
  475.       DoShadowHintProcess()
  476.       DoShadowInProcess()
  477.       Introduction.doc has some examples of the usage of this function.
  478.  
  479. NAME
  480.       DoSuperShadow -- Front-end to DSM()
  481.  
  482. SYNOPSIS
  483.       result = DoSuperShadow( object, class, method, ..., METHOD_END)
  484.         d0                                   < args on stack >
  485.  
  486. FUNCTION
  487.       This function is identical to DoShadow() except that it invokes the
  488.       method from the passed class' superclass.  If the passed class is
  489.       NULL, then the method is invoked from the first superclass of the
  490.       object's class.
  491.  
  492.       If there is both a valid object and a valid class, DSM() is called
  493.       via:
  494.          DSM(INVOKE_FIND_METHOD|INVOKE_FROM_SUPER, &object)
  495.  
  496.  
  497. INPUTS
  498.       OBJECT             object; - the object to send the method to.
  499.                                     If NULL, function returns NULL
  500.       META                class; - the first "class" to check for the
  501.                                     method.  This allows you to send
  502.                                     a method to the superClass...
  503.                                     if NULL, class is set to
  504.                                      object->cob_class.  If this is NULL,
  505.                                      then the function returns NULL.
  506.       char              *method; - pointer to the selector string.
  507.       .
  508.       .  <--- other arguments to your method
  509.       .
  510.  
  511. OUTPUTS
  512.       void *result; - result from DSM()
  513.  
  514.  
  515. RESULT
  516.       Result is dependent on the method invoked.
  517.  
  518. BUGS
  519.       none known.
  520.  
  521. NOTES
  522.  
  523. SEE ALSO
  524.       DSM()
  525.       ShadowLibraryMethods.doc and Introduction.doc have copious examples
  526.       of the usage of this function.
  527.  
  528. NAME
  529.       DoSuperShadowAsync -- Front-end to DSM()
  530.  
  531. SYNOPSIS
  532.       result = DoSuperShadowAsync( object, class, method, ..., METHOD_END)
  533.         d0                                         < args on stack >
  534.  
  535. FUNCTION
  536.       This function is identical to DoShadowAsync() except that it invokes
  537.       the method from the passed class' superclass.  If the passed class is
  538.       NULL, then the method is invoked from the first superclass of the
  539.       object's class
  540.  
  541.       DSM() is called in the following manner:
  542.  
  543.             DSM(INVOKE_FIND_METHOD | INVOKE_FORCE_ASYNC | INVOKE_FROM_SUPER,
  544.                 &object)
  545.  
  546.  
  547. INPUTS
  548.       OBJECT             object; - the object to send the method to.
  549.                                     If NULL, function returns NULL
  550.       META                class; - the first "class" to check for the
  551.                                     method.  This allows you to send
  552.                                     a method to the superClass...
  553.                                     if NULL, class is set to
  554.                                      object->cob_class.  If this is NULL,
  555.                                      then the function returns NULL.
  556.       char              *method; - pointer to the selector string.
  557.       .
  558.       .  <--- other arguments to your method
  559.       .
  560.  
  561. OUTPUTS
  562.       void *result; - result from DSM()
  563.  
  564.  
  565. RESULT
  566.       Result is dependent on the method invoked.
  567.  
  568. BUGS
  569.       none known.
  570.  
  571. NOTES
  572.  
  573. SEE ALSO
  574.       DSM()
  575.       DoShadowAsync()
  576.       Introduction.doc has some examples of the usage of this function.
  577.  
  578. NAME
  579.       DoSuperShadowHintProcess -- Front-end to DSM()
  580.  
  581. SYNOPSIS
  582.       result = DoSuperShadowHintProcess( process, object, class,
  583.                                           method, ..., METHOD_END)
  584.         d0                                 < args on stack >
  585.  
  586. FUNCTION
  587.       This function is identical to DoShadowHintProcess() except that it
  588.       invokes the method from the passed class' superclass.  If the passed
  589.       class is NULL, then the method is invoked from the first superclass
  590.       of the object's class
  591.  
  592.       DSM() is called in following manner:
  593.             DSM(INVOKE_FIND_METHOD | INVOKE_WITH_PROCESS | INVOKE_FROM_SUPER,
  594.                 &object)
  595.  
  596.  
  597. INPUTS
  598.       OBJECT            process; - the process object to try invoking the
  599.                                     the method in.
  600.       OBJECT             object; - the object to send the method to.
  601.                                     If NULL, function returns NULL
  602.       META                class; - the first "class" to check for the
  603.                                     method.  This allows you to send
  604.                                     a method to the superClass...
  605.                                     if NULL, class is set to
  606.                                      object->cob_class.  If this is NULL,
  607.                                      then the function returns NULL.
  608.       char              *method; - pointer to the selector string.
  609.       .
  610.       .  <--- other arguments to your method
  611.       .
  612.  
  613. OUTPUTS
  614.       void *result; - result from DSM()
  615.  
  616.  
  617. RESULT
  618.       Result is dependent on the method invoked.
  619.  
  620. BUGS
  621.       none known.
  622.  
  623. NOTES
  624.  
  625. SEE ALSO
  626.       DSM()
  627.       DoShadowHintProcess()
  628.       Introduction.doc has some examples of the usage of this function.
  629.  
  630. NAME
  631.       DoSuperShadowInProcess -- Front-end to DSM()
  632.  
  633. SYNOPSIS
  634.       result = DoSuperShadowInProcess( process, object, class,
  635.                                         method, ..., METHOD_END)
  636.         d0                               < args on stack >
  637.  
  638. FUNCTION
  639.       This function is identical to DoShadowInProcess() except that
  640.       it invokes the method from the passed class' superclass.  If the
  641.       passed class is NULL, then the method is invoked from the first
  642.       superclass of the object's class
  643.  
  644.       DSM() is called in following manner:
  645.             DSM(INVOKE_FIND_METHOD | INVOKE_WITH_PROCESS |
  646.                  INVOKE_FORCE_SYNC | INVOKE_FROM_SUPER,
  647.                 &object)
  648.  
  649.  
  650. INPUTS
  651.       OBJECT            process; - the process object to invoke the
  652.                                     the method in.
  653.       OBJECT             object; - the object to send the method to.
  654.                                     If NULL, function returns NULL
  655.       META                class; - the first "class" to check for the
  656.                                     method.  This allows you to send
  657.                                     a method to the superClass...
  658.                                     if NULL, class is set to
  659.                                      object->cob_class.  If this is NULL,
  660.                                      then the function returns NULL.
  661.       char              *method; - pointer to the selector string.
  662.       .
  663.       .  <--- other arguments to your method
  664.       .
  665.  
  666. OUTPUTS
  667.       void *result; - result from DSM()
  668.  
  669.  
  670. RESULT
  671.       Result is dependent on the method invoked.
  672.  
  673. BUGS
  674.       none known.
  675.  
  676. NOTES
  677.  
  678. SEE ALSO
  679.       DSM()
  680.       DoShadow()
  681.       DoShadowHintProcess()
  682.       DoShadowInProcess()
  683.       Introduction.doc has some examples of the usage of this function.
  684.  
  685. NAME
  686.       DoSuperShadowInProcessAsync -- Front-end to DSM()
  687.  
  688. SYNOPSIS
  689.       result = DoSuperShadowInProcessAsync( process, object, class,
  690.                                              method, ..., METHOD_END)
  691.         d0                                    < args on stack >
  692.  
  693. FUNCTION
  694.       This function is identical to DoShadowInProcessAsync() except
  695.       that it invokes the method from the passed class' superclass.  If the
  696.       passed class is NULL, then the method is invoked from the first
  697.       superclass of the object's class
  698.  
  699.       DSM() is called in the following manner:
  700.             DSM(INVOKE_FIND_METHOD | INVOKE_WITH_PROCESS |
  701.                  INVOKE_FORCE_ASYNC | INVOKE_FROM_SUPER,
  702.                 &object)
  703.  
  704.  
  705. INPUTS
  706.       OBJECT            process; - the process object to invoke the
  707.                                     the method in.
  708.       OBJECT             object; - the object to send the method to.
  709.                                     If NULL, function returns NULL
  710.       META                class; - the first "class" to check for the
  711.                                     method.  This allows you to send
  712.                                     a method to the superClass...
  713.                                     if NULL, class is set to
  714.                                      object->cob_class.  If this is NULL,
  715.                                      then the function returns NULL.
  716.       char              *method; - pointer to the selector string.
  717.       .
  718.       .  <--- other arguments to your method
  719.       .
  720.  
  721. OUTPUTS
  722.       void *result; - result from DSM()
  723.  
  724.  
  725. RESULT
  726.       Result is dependent on the method invoked.
  727.  
  728. BUGS
  729.       none known.
  730.  
  731. NOTES
  732.  
  733. SEE ALSO
  734.       DSM()
  735.       DoShadow()
  736.       DoShadowHintProcess()
  737.       DoShadowInProcess()
  738.       DoShadowInProcessAsync()
  739.       Introduction.doc has some examples of the usage of this function.
  740.  
  741. NAME
  742.       HandleMessages -- Handle all incoming SHADOW messages, return when
  743.                          ^C is hit.
  744.  
  745. SYNOPSIS
  746.       HandleMessages()
  747.  
  748. FUNCTION
  749.       Handle all incoming messages in the ATTR_SHADOWPROCESS' jp_port and
  750.       jp_replyPort, and returns when a ^C is sensed.
  751.  
  752.       This function actually invokes a METH_PROC_HANDLER on the current
  753.       process.  The default PROCESS_CLASS defines the above behaviour,
  754.       you may define your own, of course.
  755.  
  756.       As of SHADOW V, the function has been redefined as a macro and
  757.       resides in the shadow_proto.h file.
  758.  
  759.  
  760. INPUTS
  761.  
  762. OUTPUTS
  763.  
  764. RESULT
  765.       When the method returns, there was a ^C sensed, or whatever
  766.       conditions that could cause one of your programs to exit their
  767.       METH_PROC_HANDLER method.
  768.  
  769. BUGS
  770.       none known.
  771.  
  772. NOTES
  773.  
  774. SEE ALSO
  775.       ParseShadowMessage()
  776.       JunkIPCMessage()
  777.  
  778. NAME
  779.       PreParseShadow -- Front-end to DSM()
  780.  
  781. SYNOPSIS
  782.       message = PreParseShadow( object, class, method, ..., METHOD_END)
  783.         d0                                      < args on stack >
  784.  
  785. FUNCTION
  786.       This function is another front-end to DSM().
  787.  
  788.       This function is useful for obtaining a method invocation, and then
  789.       sending out the method at some later time and/or with some return
  790.       port that you manage.  The latter is useful when trying to simulate
  791.       the way the Amiga's asynchronous message handling hass been
  792.       historically managed (SHADOW's asynchronous methods HAVE no
  793.       replyport...).
  794.  
  795.       The following code is an example.  Remember that the jp_port and the
  796.       jp_replyport are owned by SHADOW, and are not for your use!
  797.       Therefore, you will need to define your own replyport to receive
  798.       the replies of this message.
  799.  
  800.          /*
  801.           * Create a message to handle a method invocation.
  802.           */
  803.          message = PreParseShadow(object, NULL, METH_MINE_ALL_MINE,
  804.                                                 DaffyDuck,
  805.                                                 METHOD_END);
  806.          /*
  807.           * Set the replyport for this message to return to when method
  808.           * has finished.
  809.           */
  810.          message->ipc_Msg.mn_ReplyPort = my_replyport;
  811.  
  812.          /*
  813.           * The resource tracking required to keep our process alive until
  814.           * this message has been responded to.  Note that there is a hack
  815.           * in the message creation code that leaves the last item blank
  816.           * for your usage -- this is what we now do!
  817.           */
  818.          item = &message->ipc_Items[message->ipc_ItemCount - 1];
  819.          item->ii_Id = 'JOBJ';
  820.          item->ii_Ptr = UseObject(CurrentProcess());
  821.          item->ii_Flags = IPC_TRANSFER | IPC_NONSTANDARD;
  822.  
  823.          /*
  824.           * Find destination port for method invocation.
  825.           *
  826.           * At this point we could just call ParseShadowMessage() to have
  827.           * the method performed in this task, and the reply put on our
  828.           * replyport, but that seems a bit ridiculous....
  829.           */
  830.          destProcObject = GetMyDestinationProcessObject();
  831.  
  832.          sp = (struct ShadowProcess *)
  833.                   FindAttribute(destProcObject, ATTR_SHADOWPROCESS);
  834.          if (!(PutIPCMsg(sp->sp_port, message)))
  835.             JunkIPCMessage(message);
  836.  
  837.          DropObject(destProcObject);
  838.  
  839.          .
  840.          .
  841.          .
  842.  
  843.          /*
  844.           * Now, when we receive the reply.
  845.           */
  846.          message = GetIPCMessage(my_replyport);
  847.          /*
  848.           * Get the return value.
  849.           */
  850.          return_value = message->ipc_Items[0].ii_Ptr;
  851.          /*
  852.           * Let the message know that it doesn't own the pointer anymore,
  853.           * we do.
  854.           */
  855.          IpcItemTransfer(0, message);
  856.          /*
  857.           * Get rid of the message
  858.           */
  859.          JunkIPCMessage(message);
  860.          /*
  861.           * Do something with the return value.  Free it, DropObject() it,
  862.           *  DropString() it, whatever when done using it.
  863.           */
  864.  
  865.       As with all of the DoShadow*() functions, this function checks that
  866.       a valid (non-NULL) object is sent , and returns NULL if the object
  867.       is NULL. if there is no valid class, class is set to
  868.       object->cob_class.  If this is NULL, then the function returns NULL.
  869.  
  870.       DSM() is called via:
  871.          DSM(INVOKE_FIND_METHOD | INVOKE_RETURN_MSG, &object);
  872.  
  873.  
  874. INPUTS
  875.       OBJECT             object; - the object to send the method to.
  876.                                     If NULL, function returns NULL
  877.       META                class; - the first "class" to check for the
  878.                                     method.  This allows you to send
  879.                                     a method to the superClass...
  880.                                     if NULL, class is set to
  881.                                      object->cob_class.  If this is NULL,
  882.                                      then the function returns NULL.
  883.       char              *method; - pointer to the selector string.
  884.       .
  885.       .  <--- other arguments to your method
  886.       .
  887.  
  888. OUTPUTS
  889.       struct IPCMessage *result; - a message that can be sent via
  890.                                     PutIPCMessage(), or be parsed by
  891.                                     ParseShadowMessage().  If you later
  892.                                     decide not to use the message, it can
  893.                                     be discarded via the JunkIPCMessage()
  894.                                     call.
  895.  
  896.  
  897. RESULT
  898.       A new IPC message is formed with all the necessary resource tracking
  899.       and all the necessary information to ensure that the method can be
  900.       called at some future point in time via the PutIPCMsg() or the
  901.       ParseShadowMessage() calls.
  902.  
  903. BUGS
  904.       none known.
  905.  
  906. NOTES
  907.  
  908. SEE ALSO
  909.       DSM()
  910.       DoShadow()
  911.       Introduction.doc has some examples of the usage of this function.
  912.  
  913. NAME
  914.       PreParseSuperShadow -- Front-end to DSM()
  915.  
  916. SYNOPSIS
  917.       message = PreParseSuperShadow( object, class, method, ..., METHOD_END)
  918.         d0                                           < args on stack >
  919.  
  920. FUNCTION
  921.       This function is identical to PreParseShadow() except that it
  922.       invokes the method from the passed class' superclass.  If the passed
  923.       class is NULL, then the method is invoked from the first superclass
  924.       of the object's class
  925.  
  926.       DSM() is called via:
  927.          DSM(INVOKE_FIND_METHOD | INVOKE_RETURN_MSG | INVOKE_FROM_SUPER,
  928.              &object);
  929.  
  930.  
  931. INPUTS
  932.       OBJECT             object; - the object to send the method to.
  933.                                     If NULL, function returns NULL
  934.       META                class; - the first "class" to check for the
  935.                                     method.  This allows you to send
  936.                                     a method to the superClass...
  937.                                     if NULL, class is set to
  938.                                      object->cob_class.  If this is NULL,
  939.                                      then the function returns NULL.
  940.       char              *method; - pointer to the method string.
  941.       .
  942.       .  <--- other arguments to your method
  943.       .
  944.  
  945. OUTPUTS
  946.       struct IPCMessage *result; - a message that can be sent via
  947.                                     PutIPCMessage(), or be parsed by
  948.                                     ParseShadowMessage().  If you later
  949.                                     decide not to use the message, it can
  950.                                     be discarded via the JunkIPCMessage()
  951.                                     call.
  952.  
  953.  
  954. RESULT
  955.       A new IPC message is formed with all the necessary resource tracking
  956.       and all the necessary information to ensure that the method can be
  957.       called at some future point in time via the PutIPCMsg() or the
  958.       ParseShadowMessage() calls.
  959.  
  960. BUGS
  961.       none known.
  962.  
  963. NOTES
  964.  
  965. SEE ALSO
  966.       DSM()
  967.       DoShadow()
  968.       PreParseShadow()
  969.       Introduction.doc has some examples of the usage of this function.
  970.  
  971. NAME
  972.       SprintfCallback -- sprintf callback for RawDoFmt.  [shadow.lib]
  973.  
  974. SYNOPSIS
  975.       SprintfCallback(c, text);
  976.                       d0  a3
  977. FUNCTION
  978.       This function performs the parsing RawDoFmt requires for
  979.       an sprintf() type function.
  980.  
  981.       Example:
  982.  
  983.          /*
  984.           * Put the formatted string with the address of name2
  985.           * into the buffer.
  986.           */
  987.       RawDoFmt("Object at: %lx", &name2, SprintfCallback, buffer);
  988.  
  989. INPUTS
  990.       char     c; - the character to insert
  991.       char *text; - the string to insert it into.
  992.  
  993. OUTPUTS
  994.       a3 pointer is incremented
  995.  
  996.  
  997. RESULT
  998.  
  999. BUGS
  1000.       none known.
  1001.  
  1002. NOTES
  1003.  
  1004. SEE ALSO
  1005.